CLI Reference

CLI Reference

Everything Codexify accepts on the command line. The public command groups are quickstart, projects list, and service …, plus the default (no subcommand) server mode that runs the MCP bridge directly.

Precedence: CLI flags always override values from codexify.config.json. A missing config file is tolerated; built-in defaults are used and the startup banner says so.

---

codexify (server mode)

Running with no subcommand starts the MCP bridge server. This is the mode ChatGPT connects to.

codexify --work-dir /path/to/your/project

Server flags

Flag	Required	Default	What it does
--work-dir <DIR>	Conditional	workDir	The project directory. With --multi-project (or projects list) it becomes an access root instead of the active project. Required only when the selected config does not set workDir.
--multi-project	No	Disabled	Turn --work-dir into an access root: each ChatGPT conversation binds once to a project beneath it. Other clients fall back to a transport-session binding. See Multi-Project Mode.
--worktree-mode <MODE>	No	auto	Worktree policy in multi-project mode: auto, always, or never. See Worktree Isolation.
--worktree-root <DIR>	No	Codex worktree location	Parent directory for managed conversation worktrees.
--project-clone-dir <DIR>	No	Multi-project access root	Directory where set_project_root clones requested Git repositories that have no matching local checkout. It must resolve inside the access root.
--port <PORT>	No	3000	Server port (legacy/external mode). Native tunnel mode binds loopback regardless.
--api-key <KEY>	No	—	Require Authorization: Bearer <key> on all requests except /health. Cannot be combined with native tunnel mode (which owns its own token).
--config <PATH>	No	CODEXIFY_CONFIG, then ~/.codexify/codexify.config.json	Explicit config file path (highest priority). Relative paths resolve from the startup directory; tolerated if missing. See config discovery below.
--codex-cli	No	Auto when available	Require successful Codex CLI-backed MCP discovery. Without it, a discovery failure is only a warning and direct config.toml parsing remains the fallback.
-v, --verbose	No	Info logs	Enable debug diagnostics; repeat (-vv) for trace. --log-tool-calls is an alias. See Audit Logging.
--audit <FILE>	No	Disabled	Append privacy-preserving tool-activity events to a JSONL file. --audit-log is an alias.
--audit-command-preview	No	Disabled	Add bounded, redacted previews of exec_command/run_command to the audit log.
--audit-redact-env <NAME>	No	—	Redact the current value of an env var from command previews. Repeatable.
--openai-tunnel-id <ID>	No	—	Existing OpenAI Secure MCP Tunnel ID; enables native tunnel mode.
--openai-tunnel-api-key-ref <REF>	No	env:CONTROL_PLANE_API_KEY	Runtime key reference: env:NAME or file:/path. Literal keys are rejected.
--openai-tunnel-client <PATH>	No	Managed pinned runtime	Use an explicit tunnel-client / tunnel-client-runtime binary instead of the managed one.
--openai-tunnel-organization-id <ID>	No	—	Optional OpenAI organization ID sent by the tunnel client.

Project root requirement

Codexify needs a project root from either --work-dir or the top-level workDir config key. In single-project mode that value is the project root; in multi-project mode it is the access boundary beneath which projects are selected. Background-service launches normally use workDir from the config. Nothing a structured filesystem tool does can escape the active project root (with one bounded, read-only exception for AGENTS.md discovery — see Security Model).

Common invocations

# Simplest: single project, native tunnel configured in codexify.config.json
codexify --work-dir ~/code/myapp

# Many projects from one server
codexify --work-dir ~/code --multi-project

# Verbose diagnostics while debugging a connector
codexify -v --work-dir ~/code/myapp

# With an audit trail (safe subset by default)
codexify --work-dir ~/code/myapp --audit ~/.codexify/audit/tools.jsonl

# Native tunnel entirely from flags (no config file)
codexify --work-dir ~/code/myapp \
  --openai-tunnel-id tunnel_0123... \
  --openai-tunnel-api-key-ref env:CONTROL_PLANE_API_KEY

Logging levels

The default tracing level is info.

• -v → codexify=debug,rmcp=warn: adds tool-start events, hashed conversation/project context, argument field names, duration, and output accounting — without dumping protocol traffic.

• -vv → codexify=trace, rmcp stays at warn: adds a fully redacted argument-shape summary.

• An explicit RUST_LOG env var overrides -v/-vv when you need protocol-level detail:

  RUST_LOG=codexify=trace,rmcp=warn codexify --work-dir ~/code/myapp

---

codexify quickstart

Interactive setup wizard. Configures project scope, native OpenAI tunnel credentials, the JSON config, and the ChatGPT developer-mode connector — and can start the server when done. See Quick Start.

Flag	Default	What it does
--config <PATH>	CODEXIFY_CONFIG, then ~/.codexify/codexify.config.json	Which config file the wizard writes. By default it writes the user-level config (creating ~/.codexify/ if needed); pass --config or set CODEXIFY_CONFIG to write elsewhere.
--work-dir <DIR>	—	Initial value for the project-directory prompt.

codexify quickstart
codexify quickstart --config ~/servers/codexify.config.json --work-dir ~/code/myapp

---

codexify projects list

A local diagnostic for the project catalogue used in multi-project mode. It does not start the HTTP server, the tunnel, or any bridged MCP children — it just prints what would be selectable.

codexify projects list --work-dir /path/to/projects
codexify projects list --work-dir /path/to/projects --query "codexify"
codexify projects list --work-dir /path/to/projects --json
codexify projects list --work-dir /path/to/projects --show-skipped

Flag	Default	What it does
--work-dir <DIR>	— (required)	The access root whose catalogue to enumerate.
--query <TEXT>	—	Filter candidates by name, alias, description, or relative selector.
--limit <N>	Max project limit	Cap the number of results.
--json	Off	Emit machine-readable JSON.
--show-skipped	Off	Also print paths rejected as missing, untrusted, or outside the access root, plus merged duplicates.

--show-skipped is deliberately local-only: normal CLI output and the list_projects tool expose only aggregate warnings, so an agent never learns absolute paths it cannot select.

---

codexify service …

The release installers register a per-user service. These commands manage it directly:

Command	What it does
codexify service install	Create/update the native per-user service using the selected config and start it.
codexify service enable	Enable and start an installed service.
codexify service disable	Stop and disable an installed service.
codexify service logs	Print the rotating service log.
codexify service logs -f	Follow the service log.
codexify service remove	Stop and remove the service definition.

service install uses the normal config selection (--config, then CODEXIFY_CONFIG, then ~/.codexify/codexify.config.json). The internal service run command is what the OS service manager launches; it is not the normal way to start Codexify manually. See Installation.

---

See also

• Configuration — the codexify.config.json equivalents of these flags, and everything that has no flag.
• Security Model — what --work-dir, --api-key, and the allowlists actually bound.
• Connecting to ChatGPT — the --openai-tunnel-* flags in context.